% epydoc -- Demo & description of latex writer output
%
% Copyright (C) 2008 Edward Loper
% Author: Edward Loper <edloper@loper.org>
% URL: <http://epydoc.sf.net>
%
% $Id: apidoc.py 1729 2008-02-19 16:49:16Z edloper $

% This is the basic preamble that's always included (in the api.tex file).
% If any reStructuredText docstrings are used, then it is extended using
% the preamble material used by reStructuredText.
\documentclass{article}
\usepackage[index]{epydoc}
\usepackage[utf8]{inputenc}
\definecolor{UrlColor}{rgb}{0,0.08,0.45}
\usepackage[pdftex, pagebackref, pdftitle={API Documentation}, %
  pdfcreator={epydoc 3.0.1}, bookmarks=true, bookmarksopen=false, %
  pdfpagemode=UseOutlines, colorlinks=true, linkcolor=black, %
  anchorcolor=black, citecolor=black, filecolor=black, menucolor=black, %
  pagecolor=black, urlcolor=UrlColor]{hyperref}
\begin{document}

\title{Epydoc LaTeX Writer Output Demo}
\author{}
\date{}
\maketitle

This file provides a demonstration and description of epydoc's LaTeX
output.  Most of the important information is in the comments, so you
should read this file in its original form (and not as a rendered pdf).
By looking at this file, and at the epydoc-default.sty file, you should
be able to determine how to write your own customized style file.

% ======================================================================

\section{General Formatting}

\subsection{Hyperlinks and Crossreferences}

% The \EpydocDottedName command is used to escape dotted names.  In
% particular, it escapes underscores (_) and allows non-hyphenated
% wrapping at '.' separator characters.
\EpydocDottedName{my_module.Zip}

% The \EpydocHypertarget command is used to mark targets that hyperlinks
% may point to.  It takes two arguments: a target label, and text
% contents.  (In some cases, the text contents will be empty.)  Target
% labels are formed by replacing '.'s in the name with ':'s.  The
% default stylesheet creates a \label for the target label, and displays
% the text.
\EpydocHypertarget{foo:bar:baz}{\EpydocDottedName{foo.bar.baz}}

% The \EpydocHyperlink command is used to create a link to a given target.
% It takes two arguments: a target label, and text contents.  The
% default stylesheet just displays the text contents.
\EpydocHyperlink{foo:bar:baz}{\EpydocDottedName{foo.bar.baz}}

% The \CrossRef command creates a cross-reference to a given target,
% including a pageref.  It takes one argument, a target label.
\CrossRef{foo:bar:baz}

\subsection{Indexing}

% The \EpydocIndex command is used to mark items that should be included
% in the index.  It takes three arguments.  The first argument is the
% item's case-normalized name; this is typically discarded, and is
% simply used to ensure the proper (i.e., case-insensitive) sort order
% in the index.  The second argument is the item's name; and the
% third item is the item's "kind".  "kind" can be Package, Script, Module,
% Class, Class Method, Static Method, Method, Function, or Variable.
% This command is used inside of the \index{...} command.
%
% For modules and classes, the \index formatting strings "|(" and
% "|)" are appended to mark the beginning and end of the object's
% documentation.  For methods, variables, and nested classes, the
% index formatting string "!" is used to create nested index entries.
% See the docs for the latex \index command for more information.
\index{\EpydocIndex{mymodule}{mymodule}{module}|(}
\index{\EpydocIndex{foo}{Foo}{class}|(}
\index{\EpydocIndex{foo}{Foo}{class}!\EpydocIndex{foo.f}{Foo.f}{method}}
\index{\EpydocIndex{foo}{Foo}{class}!\EpydocIndex{foo.f}{Foo.g}{method}}
\index{\EpydocIndex{foo}{Foo}{class}|)}
\index{\EpydocIndex{mymodule}{mymodule}{module}|)}

\subsection{Source Code Syntax Highlighting}

% Doctest blocks are colorized using a variety of commands, all beginning
% with the prefix "\pysrc".  See epydoc-default.sty for a full list.
\begin{alltt}
\pysrcprompt{{\textgreater}{\textgreater}{\textgreater} }f(x)
\pysrcoutput{123}\end{alltt}

\subsection{reStructuredText Admonitions}

% These would be defined by rst's style file:
\newlength{\admonitionwidth}
\setlength{\admonitionwidth}{.8\textwidth}

% The reSTadmonition environment is used to display reStructuredText 
% admonitions, such as ``..warning::'' and ``..note::''.  It takes
% one optional argument, the admonition type.
\begin{reSTadmonition}[note]
  This is a note.
\end{reSTadmonition}

\subsubsection{Sections inside Docstrings}

% The commands \EpydocUserSection, \EpydocUserSubsection, and
% \EpydocUserSubsubsection are used to add section headings inside
% of docstrings
\EpydocUserSection{Intra-docstring heading 1}
\EpydocUserSubsection{Intra-docstring heading 2}
\EpydocUserSubsubsection{Intra-docstring heading 3}

% ======================================================================

% Each module is listed in its own section.  (These sections are created
% as separate files, and \include-ed into the main api.tex file).  The
% section contains:
%   - The module description (from the module's docstring)
%   - A metadata section (author, version, warnings, etc)
%   - A list of submodules (if it's a package)
%   - A list of classes defined by the module (only if the
%     --list-classes-separately option is used).
%   - A subsection describing the functions defined by the module.
%   - A subsection describing the variables defined by the module.
%   - A subsection for each class defined by the module (only if
%     the --list-classes-separately option is *not* used).
\section{my\_module}

  % The EpydocModuleDescription environment is used to mark the
  % module's description (from its docstring)
  \begin{EpydocModuleDescription}
  This is an example module, used to demonstrate the LaTeX commands and
  environments used by epydoc.
  \end{EpydocModuleDescription}
  
  % Each metadata item is listed separately.  There are three environments
  % and commands used for metadata:
  %   - The \EpydocMetadataSingleValue command is used to display a metadata
  %     field with a single value.  It takes two arguments: the metadata
  %     field name and the metadata description.
  %   - The \EpydocMetadataShortList environment is used to display a
  %     metadata field with multiple values when the field declares that
  %     short=True; i.e., that multiple values should be combined into a
  %     single comma-delimited list.  It takes one argument (the metadata
  %     field name); and items should be separated by the \and command.
  %   - The \EpydocMetadataLongList environment is used to display a
  %     metadata field with multiple values when the field declares that
  %     short=False; i.e., that multiple values should be listed
  %     separately in a bulleted list.  It takes one argument (the metadata
  %     field name); and items should marked wit hthe \item command.
  \EpydocMetadataSingleValue{See Also}{some reference.}

  \begin{EpydocMetadataShortList}{Author}
    joe \and mary
  \end{EpydocMetadataShortList}

  \begin{EpydocMetadataLongList}{Notes}
    \item This is one note.
    \item This is a second note.
  \end{EpydocMetadataLongList}

  % The list of submodules that a package contains is put it its own
  % subsection.  The list is displayed using the EpydocModuleList
  % environment.  Nested submodules are displayed using nested
  % EpydocModuleList environments.  If the modules are divided into
  % groups (with the epydoc @group field), then groups are displayed
  % using the \EpydocGroup command, followed by a nested EpydocModuleList.
  \subsection{Submodules}
  \begin{EpydocModuleList}
    \item[\EpydocHyperlink{my_module:foo}{\EpydocDottedName{my_module.foo}}]
        Description of my\_module.foo.
    \item[\EpydocHyperlink{my_module:bar}{\EpydocDottedName{my_module.bar}}]
        Description of my\_module.bar.
        \begin{EpydocModuleList}
            \item[\EpydocHyperlink{my_module:bar:soap}
                  {\EpydocDottedName{my_module.bar.soap}}]
                Description of my\_module.bar.soap.
        \end{EpydocModuleList}
    \EpydocGroup{Some Group}
      \begin{EpydocModuleList}
        \item[\EpydocHyperlink{my_module:baz}
              {\EpydocDottedName{my_module.baz}}]
            Description of my\_module.baz.
      \end{EpydocModuleList}
  \end{EpydocModuleList}
  
  % The list of classes that a module contains is just like the list
  % of submodules that a package contains, except that the list
  % environment EpydocClassList and the command \EpydocGroup
  % are used.  (Note that this list is only included when the
  % --list-classes-separately option is used.)
  \subsection{Classes}
  \begin{EpydocClassList}
    \item[\EpydocHyperlink{my_module:Zip}
          {\EpydocDottedName{my_module.Zip}}]
        Description of my\_module.Zip.
    \item[\EpydocHyperlink{my_module:Zap}
          {\EpydocDottedName{my_module.Zap}}]
        Description of my\_module.Zap.
    \EpydocGroup{Some Group}
      \begin{EpydocClassList}
        \item[\EpydocHyperlink{my_module:Zam}
              {\EpydocDottedName{my_module.Zam}}]
            Description of my\_module.Zam.
        \item[\EpydocHyperlink{my_module:Zam}
              {\EpydocDottedName{my_module.Zam}}]
            Description of my\_module.Zam.
      \end{EpydocClassList}
  \end{EpydocClassList}
  
  % The functions that a module contains are listed in a separate
  % subsection.  This subsection contains a single EpydocFunctionList
  % environment
  \subsection{Functions}
  
  % The EpydocFunctionList  environment is used to display functions.  
  % It contains one \EpydocFunction command for each function.  This
  % command takes 8 arguments:
  % 
  %   - The function's signature: an EpydocFunctionSignature environment
  %     specifying the signature for the function.
  %
  %   - The function's description (from the docstring)
  % 
  %   - The function's parameters: An EpydocFunctionParameters list 
  %     environment providing descriptions of the function's parameters.
  %     (from the epydoc @param, @arg, @kwarg, @vararg, @type fields)
  %
  %   - The function's return description (from the epydoc @rerturns field)
  %
  %   - The function's return type (from the epydoc @rtype field)
  %
  %   - The function's exceptions: An EpydocFunctionRaises list
  %     environment describing exceptions that the function may raise
  %     (from the epydoc @raises field)
  %
  %   - The function's override: An EpydocFunctionOverrides command
  %     describing the method that this function overrides (if any)
  %
  %   - The function's metadata: Zero or more EpydocMetadata*
  %     commands/environments, taken from metadata fields (eg @author)
  %
  % All arguments except for the first (the signature) may be empty.
  %
  \begin{EpydocFunctionList}

    \EpydocFunction{
      % Argument 1: The function signature
      %
      % The EpydocFunctionSignature is used to display a function's
      % signature.  It expects one argument, the function's name.  The
      % body of the environment containd the parameter list.  The
      % following commands are used in the parameter list, to mark
      % individual parameters:
      %   - \Param: Takes one required argument (the parameter name) and
      %     one optional argument (the defaultt value).
      %   - \VarArg: Takes one argument (the varargs parameter name)
      %   - \KWArg: Takes one argument (the keyword parameter name)
      %   - \GenericArg: Takes no arguments (this is used for '...', e.g.
      %     when the signature is unknown).
      %   - \TupleArg: Used inside of the \Param command, to mark
      %     argument tuples.  Individual elements of the argument tuple
      %     are separated by the \and command.
      % 
      % Parameters are separated by the \and command.
      \begin{EpydocFunctionSignature}{myfunc}%
          \Param{x}%
          \and \Param{y}%
          \and \Param{i}%
          \and \Param{j}%
          \and \Param{\TupleArg{a \and b}}%
          \and \VarArg{rest}, \KWArg{keywords}%
      \end{EpydocFunctionSignature}
    }{
      % Argument 2: The function description
        This is an example function.
    }{
      % Argument 3: The function parameter descriptions
      %
      % The EpydocFunctionParameters list environment is used to
      % describe the function's parameters.  It takes a single
      % required argument, a string which can be used to set the
      % label width for the list.  (I.e., this string is as long
      % as the longest parameter name.)  The list contains one
      % \item for each parameter description.  Parameter types
      % are currently listed as part of the text (not using any 
      % special environments or commands)
      \begin{EpydocFunctionParameters}{xxxxxxxx}
        \item[x] Description of parameter x.
  
                 (type=int)
  
        \item[i, j] Description of parameters x and y.
  
        \item[keywords] Description of the keywords parameter.
      \end{EpydocFunctionParameters}
    }{
      % Argument 4: The function return value description
      description of the return value
    }{
      % Argument 5: The function return value tupe
      int
    }{
      % Argument 6: The function exception descriptions
      %
      % The EpydocRaises list environment is used to display the
      % list of exceptions that the function may raise.  The list
      % contains one \item for each exception.
      \begin{EpydocFunctionRaises}
        \item[ValueError] If there's some problem with a value.
        \item[TypeError] If the wrong type is given.
      \end{EpydocFunctionRaises}
    }{
      % Argument 7: The function overrides command
      %
      % (this is only used for methods, not functions)
    }{
      % Argument 8: The function metadta
      %
      % The metadata section uses the same commands that the module-
      % level metadata section uses; see the discussion above.
      \EpydocMetadataSingleValue{See Also}{some reference.}
  
      \begin{EpydocMetadataShortList}{Author}
        joe \and mary
      \end{EpydocMetadataShortList}
  
      \begin{EpydocMetadataLongList}{Notes}
        \item This is one note.
        \item This is a second note.
      \end{EpydocMetadataLongList}
    }

    % If functions are divided into groups (with the epydoc @group
    % field), then group headers are marked with the \EpydocGropu
    % command.
    \EpydocGroup{Some Group}

    \EpydocFunction{
      \begin{EpydocFunctionSignature}{\EpydocDottedName{some_func}}
          \Param{x} \and \Param{y} \and \Param{z}
      \end{EpydocFunctionSignature}}
      {}{}{}{}{}{}{}

  \end{EpydocFunctionList} 

  % The variables that a module contains are listed in a separate
  % subsection.  This section contains a single EpydocVariableList
  % environment
  \subsection{Variables}

  % The EpydocVariableList environment is used to describe module
  % variables.  It contains one \EpydocVariable command for each
  % variable.  This command takes four required arguments:
  % 
  %   - The variable's name
  %   - The variable's description (from the docstring)
  %   - The variable's type (from the epydoc @type field)
  %   - The variable's value
  %
  % If any of these arguments is not available, then the empty
  % string will be used.
  %
  % If the variables are divided into groups (with the epydoc @group
  % field), then the \EpydocInternalHeader command is used to mark
  % the beginning of each variable group.
  \begin{EpydocVariableList}
    \EpydocVariable{\EpydocHyperlink{my_module:gorp}
                    {\EpydocDottedName{my_module.gorp}}}
                   {Description of the variable gorp}
                   {int}
                   {12}
    \EpydocVariable{\EpydocHyperlink{my_module:moo}
                    {\EpydocDottedName{my_module.moo}}}
                   {Description of the variable moo}
                   {str}
                   {'hello'}
    \EpydocVariable{\EpydocHyperlink{my_module:cow}
                    {\EpydocDottedName{my_module.cow}}}
                   {} % no description
                   {} % no type
                   {} % no value
  \end{EpydocVariableList}

  % The remaineder of the module's section consists of one subsection
  % for each class defined by the module.  (However, if the
  % --list-classes-separately option is used, then these subsections
  % are not generated; instead, epydoc will generate a separate
  % top-level section for each class.)  Each class section contains:
  %   - The class's base tree (or a class tree graph, if the options
  %     "--graph classtree" or "--graph umlclasstree" are used).
  %   - A list of known subclasses.
  %   - The class description (from the class's docstring)
  %   - A metadata section (author, version, warnings, etc)
  %   - A list of methods defined by the class
  %   - A list of properties defined by the class
  %   - A list of class variables defined by the class
  %   - A list of instance variables defined by the class
  \subsection{Class \EpydocDottedName{Zip}}

    % The base tree is 'drawn' using a carefully constructed tabular
    % environment.  Here's an example of what it can look like:
    \begin{tabular}{cccccc}
    \multicolumn{2}{r}{
      \settowidth{\EpydocBCL}{\EpydocDottedName{MyBaseClass}}
      \multirow{2}{\EpydocBCL}{\EpydocHyperlink{object}
                        {\EpydocDottedName{MyBaseClass}}}}
      && \\
      \cline{3-3}
      &&\multicolumn{1}{c|}{} && \\
      &&\multicolumn{2}{l}{\textbf{\EpydocDottedName{my_module.Zip}}}
    \end{tabular}

    % The known subclasses are displayed using an \EpydocMetadataSingleValue
    % command or an \EpydocMetadataShortList environment.  See the
    % description of these above (for module metadata).
    \begin{EpydocMetadataShortList}{Known Subclasses}
      \EpydocHyperlink{my_module:Zap}{\EpydocDottedName{my_module.zap}}
      \and
      \EpydocHyperlink{my_module:Zam}{\EpydocDottedName{my_module.zam}}
    \end{EpydocMetadataShortList}

    % The EpydocClassDescription environment is used to mark the
    % class's description (from its docstring)
    \begin{EpydocClassDescription}
    This is an example class, used to demonstrate the LaTeX commands and
    environments used by epydoc.
    \end{EpydocClassDescription}
  
    % The metadata section uses the same commands that the module-
    % level metadata section uses; see the discussion above.
    \EpydocMetadataSingleValue{See Also}{some reference.}

    \begin{EpydocMetadataShortList}{Author}
      joe \and mary
    \end{EpydocMetadataShortList}

    % The methods that a class defines are listed in a separate
    % subsubsection.  This subsubsection contains a single
    % EpydocFunctionList environment.
    \subsubsection{Methods}

    % The EpydocFunction environment was described above (when it was
    % used with module-level functions.)  The only difference here is
    % that functions may optionally include a command specifying
    % what method is overridden by this method (\EpydocFunctionOverrides)
    % as the seventh argument to the \EpydocFunction command.
    \begin{EpydocFunctionList}
      \EpydocFunction{
        \begin{EpydocFunctionSignature}{mymethod}
            \Param{x} \and \Param{y}
        \end{EpydocFunctionSignature}}
        {This is an example function.}
        {}{}{}{}
        {
          % The \EpydocFunctionOverrides command specifies which method
          % was overridden by this method.  It comes just before the
          % metadata section.  It takes one optional argument, which will
          % be "1" if documentation was inherited from the overridden
          % method; and one required argument, containing the name of
          % the overridden method.
          \EpydocFunctionOverrides[1]{\EpydocHyperlink{MyBaseClass:mymethod}
                                  {\EpydocDottedName{MyBaseClass.mymethod}}}
        }{}
    \end{EpydocFunctionList}

    % The properties that a class defines are listed in a separate
    % subsection.  This section contains a single EpydocPropertyList
    % environment.
    \subsubsection{Properties}

      % The EpydocPropertyList environment is used to describe class
      % properties.  It contains one \EpydocProperty command for each
      % property.  This command takes six required arguments:
      % 
      %   - The property's name
      %   - The property's description (from the docstring)
      %   - The property's type (from the epydoc @type field)
      %   - The property's fget function
      %   - The property's fset function
      %   - The property's fdel function
      %
      % If any of these arguments is not available, then the empty
      % string will be used.
      %
      % If the properties are divided into groups (with the epydoc @group
      % field), then the \EpydocInternalHeader command is used to mark
      % the beginning of each property group.
      %
      % If any properties are inherited from a base class, and if
      % --inheritance=listed (the default), then they will be listed
      % after all the other properties, using the
      % \EpydocInheritanceList command.  This command will be used
      % once for each base class that properties are inherited from.
      % It takes two arguments: the name of the base class that the
      % properties were inherited from, and a list of property names.
      \begin{EpydocPropertyList}
        \EpydocProperty{\EpydocHyperlink{my_module:Zip:duck}
                        {\EpydocDottedName{duck}}}
                       {Description of the property duck}
                       {int}
                       {\EpydocDottedName{get_dock}}
                       {\EpydocDottedName{set_dock}}
                       {\EpydocDottedName{del_dock}}
        \EpydocInheritanceList{MyBaseClass}{goose, pig}
      \end{EpydocPropertyList}

    % The class variabless that a class defines are listed in a 
    % separate subsection.  This section contains a single 
    % EpydocClassVariableList environment.
    \subsubsection{Class Variables}

      % The EpydocClassVariableList environment is used the same way as
      % the EpydocVariableList environment (shown above), with one
      % exception: if any variables are inherited from a base class,
      % and if--inheritance=listed (the default), then they will be 
      % listed after all the other properties, using the
      % \EpydocInheritanceList command.  This command will be used
      % once for each base class that variabless are inherited from.
      % It takes two arguments: the name of the base class that the
      % properties were inherited from, and a list of property names.
      \begin{EpydocClassVariableList}
        \EpydocVariable{\EpydocHyperlink{my_module:Zip:quack}
                        {\EpydocDottedName{my_module.Zip.quack}}}
                       {Description of the class variable quack}
                       {str} % type
                       {}    % no value
        \EpydocInheritanceList{MyBaseClass}{oink, bark}
      \end{EpydocClassVariableList}

    % The instance variabless that a instance defines are listed in a 
    % separate subsection.  This section contains a single 
    % EpydocInstanceVariableList environment.
    \subsubsection{Instance Variables}

      % The EpydocInstanceVariableList environment is used the same 
      % way as the EpydocClassVariableList environment (shown above).
      \begin{EpydocClassVariableList}
        \EpydocVariable{\EpydocHyperlink{my_module:Zip:florp}
                        {\EpydocDottedName{my_module.Zip.flrop}}}
                       {Description of the class variable florp}
                       {list} % type
                       {}     % no value
        \EpydocInheritanceList{MyBaseClass}{blorp}
      \end{EpydocClassVariableList}

% That's all, folks!
\end{document}
